Skip to content

Conversation

@s-makin
Copy link
Collaborator

@s-makin s-makin commented Nov 24, 2025

Description

This PR updates us to the newest version (1.3.0 currently) of the Canonical Starter Pack (extension version). Future updates should be easier, as the directory structure now matches the Starter Pack.

Changes made (that don't need review):

  • Most files have been moved without changes into the docs/ dir.
    • Doc templates, .github and .readthedocs.yaml are still at the root
  • Many files have been consolidated:
    • Spelling and inclusivity check exceptions all go into docs/.custom_wordlist.txt
    • Makefiles
    • Our custom config now all goes into docs/conf.py
  • All custom css, js and html templates are in docs/.sphinx/
  • Automated checks now use Vale on the backend, and are much faster
  • All restructuredtext-only content has been removed
  1. 99% of files are moved without changing, so can be skipped.
  2. I disabled the automatic doc checks as the Vale implementation is very stringent. I will clear the failures and re-enable the checks in a follow-up PR.

Special points for reviewers

GH Copilot helped me resolve some of the blockers. I'd like a second opinion on these changes to ensure they're acceptable:

  • docs/.sphinx/_templates/footer.html

    • GHC resolved the template overrides so we keep our GH links in the footer.
  • ./Makefile

    • GHC created a Makefile wrapper at root so the make commands can be run anywhere
  • docs/.sphinx/_templates/header.html

    • Cookie banner JS file was not being picked up. GHC removed a hardcoded path in header.html on the basis that conf.py contains the path to the bundle.js file and is injected onto every page by default.
  • Feedback button wasn't picking up the link to the issue template:

    • docs/.sphinx/_templates/page.html: GHC added a <meta> tag to expose the github_url variable to JS. It also changed from window.onload to DOMContentLoaded for better performance.
    • docs/.sphinx/_static/js/github_issue_links.js: now reads github_url from the meta tag

Checklist

  • I have read and followed the Ubuntu Server contributing guide.
  • My pull request is linked to an existing issue (if applicable).
  • I have tested my changes, and they work as expected.

@s-makin s-makin marked this pull request as draft November 24, 2025 17:23
@s-makin s-makin marked this pull request as ready for review November 27, 2025 14:37
@s-makin s-makin merged commit 0beb74f into canonical:main Nov 28, 2025
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant